<html>
<head>
<title>reification howto</title>
<link href="../styles/doc.css" rel="stylesheet" type="text/css">
</head>
<body>
<h1>reification howto</h1>
<b>author</b>: Chris Dollin
<br><b>version</b>: 1.0
<br><b>id</b>: $Id: reification.html,v 1.8 2003/08/28 11:29:05 andy_seaborne Exp $

<h2>introduction</h2>

This document describes the Jena 2 reification API and how to use it.
New users of Jena should read this to understand Jena's special support
for reification. Since there have been significant changes to this
support since Jena 1, users of Jena 1's reification should also read 
this document to see how to translate their existing code to the new form.
As always, consult the Javadoc for interface details.

<p>Reification in RDF and Jena is the ability to treat a <code>Statement</code>
as a <code>Resource</code>, and hence to make assertions <i>about</i> that
statement. A statement may be reified as many different
resources, allowing different manifestations ("statings") of
that statement to be treated differently if required.

<p>RDF represents a reified statement as four statements with
particular RDF properties and objects: the statement 
<code>(S, P, O)</code>, reified by resource <code>R</code>, is represented by:

<ul>
<li><code>R rdf:type rdf:Statement</code></li>
<li><code>R rdf:subject S</code></li>
<li><code>R rdf:predicate P</code></li>
<li><code>R rdf:object O</code></li>
</ul>

<p>We shall call these four such statements a <i>reification quad</i>
and the components <i>quadlets</i>. Users of reification in Jena
may, by default, simply manipulate reified statements as these quads.
However, just as for <code>Bag</code>, <code>Seq</code>, 
<code>Alt</code> and <code>RDF lists</code> in ordinary models, 
or ontology classes and individuals in <code>OntModel</code>s, 
Jena has additional support for manipulating reified statements. 
It also optimises the storage for complete reification quads,
avoiding having to store the extra four statements merely to
represent one reification.

<p>The interface <code>ReifiedStatement</code> is used to represent
a reified statement as a Jena <code>Resource</code> that has direct access to
the statement it reifies. The method

<ul><li><code>ReifiedStatement::getStatement()</code></li></ul>

returns the <code>Statement</code> that the resource is reifying.
All the other <code>Resource</code> methods, of course, may be applied
to a <code>ReifiedStatement</code>.

<h2>converting resources to reified statements</h2>

If a resource <code>R</code> is associated with a reified statement,
but might not itself be a <code>ReifiedStatement</code> object, the
conversion method <code>RDFNode::as(Class)</code> can be used to
find (or create) a <code>ReifiedStatement</code>:

<ul><li><code>(ReifiedStatement) R.as(ReifiedStatement.class)</code></li></ul>

For example, a model that has been read in from an RDF/XML file
may have reified statements: knowing the name of the resource
allows a ReifiedStatement object to be constructed without
knowing the statement itself.

<p>If there is no such associated reified statement,
a <code>CannotReifyException</code> is thrown. To find out in
advance if the conversion is possible, use the predicate
<code>RDFNode::canAs(ReifiedStatement.class)</code>. (Jena
only counts as "an associated reified statement" a resource
with exactly one <code>rdf:subject</code>, <code>rdf:predicate</code>,
 and <code>rdf:object</code> which has <code>rdf:type rdf:Statement</code>.
 It can of course have <i>other</i> properties.)

<p>Once the <code>ReifiedStatement</code> has been constructed,
it retains its <code>Statement</code> even if some (or all)
of the original quadlets are removed from the model. This is
a feature of the current implementation that might go away; do
not rely on it.

<h2>testing statements for reification</h2>

You may wish to know if some <code>Statement</code> is reified.
The methods <code>Statement::isReified()</code> and 
<code>Model::isreified(Statement)</code> return true if (and only if)
the statement has been reified in the model. Note that the
<code>Statement</code> method tests to see if the statement
is reified in its own model, and the model method tests to 
see if the <code>Statement</code> is reified in <i>that</i>
model; there is no test to see if a <code>Statement</code>
is reified in any other models.

<h2>listing reified statements</h2>

Just as <code>listStatements</code> is used to find the
statements present in some model, there are methods for
finding the reified statements of a model. Each of them returns 
a <code>RSIterator</code> object, which is an
iterator each of who's elements are <code>ReifiedStatement</code>s and
for which the convenience method <code>nextRS()</code> will deliver
a suitably-cast reified statement.

<ul>
<li><code>Statement::listReifiedStatements()</code> -
all the reifications of this statement in its model.
</li>
<li><code>Model::listReifiedStatements()</code> -
all the reified statements in this model.
</li>
<li><code>Model::listReifiedStatements(Statement s)</code> -
all the reified statements reifiying <code>s</code> in this model.
</li>
</ul>

<h2>creating reified statements directly</h2>

You do not have to create reified statements by asserting their
quads into a <code>Model</code>; they can be created directly 
from their <code>Statement</code>s using one of the methods:

<ul>
<li><code>Statement::createReifiedStatement()</code></li>
<li><code>Statement::createReifiedStatement(String)</code></li>
<li><code>Model::createReifiedStatement(Statement)</code></li>
<li><code>Model::createReifiedStatement(String,Statement)</code></li>
</ul>

Each of these returns a <code>ReifiedStatement</code> who's
<code>getStatement()</code> method delivers the original statement
(actually, a <code>.equals()</code> statement; it may not be
the identical statement). If the creation method passed
in a (non-null) <code>String</code>, the <code>ReifiedStatement</code> 
is a named resource and that string is its URI. Otherwise it is a newly-minted
bnode. The methods on <code>Statement</code> create a reified statement
in that statements model; those on <code>Model</code> create a reified statement
in that model.

<p>It is not permitted for two different (non-equals) statements 
to be reified onto the same resource. An attempt to do so will 
generate an <code>AlreadyReifiedException</code>.

<p>The additional method <code>Model::getAnyReifiedStatement(Statement)</code>
returns some reification of the supplied <code>Statement</code>; an
existing one if possible, otherwise a fresh one (reified by a 
fresh bnode).

<h2>reification and Model::add(Model)</h2>

When one model is added to another, as well as the ordinary statements
of the model being added, the reified statements are copied across. If
this is not desired, there is a two-argument form:

<ul><li>Model::add(Model m, boolean suppress)</li></ul>

If <code>suppress</code> is <code>true</code>, then the reified statements are
not copied. (This choice arose from comments on earlier versions
of the Jena 2 API; users expected the reified statements to be copied.)

<h2>removing reified statements</h2>

There are two methods which remove all the reifications of a
<code>Statement</code> in some <code>Model</code>:

<ul>
<li><code>Statement::removeReification()</code></li>
<li><code>Model::removeAllReifications(Statement)</code></li>
</ul>

All the reified statements in the model that reify
the given statement are removed, whatever their reifying resource.
To remove a particular reified statement only, use

<ul><li><code>Model::removeReification(ReifiedStatement)</code></li></ul>

Similarly to <code>Model::add(Model)</code>, the method 
<code>model.remove(Model m)</code> will remove all the reified statements
of <code>m</code> from <code>model</code>, and the two-argument form
<code>model.remove(m,true)</code> will not.

<h2>reification styles</h2>

By default and as you might expect, Jena models allow reification
quads to be manifested as <code>ReifiedStatement</code>s. Similarly,
explicitly created <code>ReifiedStatement</code>s are visible as
statement quads.

<p>Sometimes this is not desirable. For example, in an application
that reifies large numbers of statements in the same model as those
statements, most of the results from <code>listStatements()</code>
will be quadlets; this is inefficient and confusing. One choice is
to reify the statements in a <i>different</i> model. Another is
to take advantage of <i>reification styles</i>.

<p>Each model has a reification style, described by constants in
<code>ModelFactory</code>. The default style is called 
<code>Standard</code> because it behaves mostly closely to
the RDF standard. There are two other reification styles to choose
from:

<ul>
<li><code>Convenient</code>: reification quadlets are not visible
in the results of <code>listStatements)()</code>. Otherwise
everything is normal; quadlets that are added to the model contribute
to <code>ReifiedStatement</code> construction.</li>

<li><code>Minimal</code>: reification quadlets play no role at
all in the construction of <code>ReifiedStatement</code>s, which
can only be created by the methods discussed earlier. This style is
most similar to that of Jena 1.
</li>
</ul>

The method <code>ModelFactory.createDefaultModel()</code> takes an
optional <code>Style</code> argument, which defaults to 
<code>Standard</code>. Similarly, <code>createFileModelMaker()</code>
and <code>createMemModelMaker()</code> can take <code>Style</code>
arguments which are applied to every model they create.

<p>To take a model with hidden reification quads and expose them as
statements, the method <code>ModelFactory.withHiddenStatements(Model m)</code> 
produces a new model which does just that.

</body>
</html>
